Summary

针对 skill/ 目录做结构化优化，解决上一轮代码评审识别的 14 处 P0/P1/P2 矛盾与缺口，让 skill 在使用过程中更平滑、对用户指令更友好。

• 自洽性修复（P0）：spec 路径单复数不一致（spec/ → specs/<编号>-*/）、argument-hint 非法 frontmatter 字段、模板 main.py 与 phase3 文档冲突、router/ 残留目录——全部闭环
• 入口总览 + Phase 0 外置：SKILL.md 瘦身 330 → 142 行；新建 phases/phase0.md（240 行）承载完整 Step 0-1~0-8；SKILL.md 顶部新增 ## 适用版本（nexusx >= 3.2）+ ## 调用约定，让新人 5 分钟可入门
• 模板完整性：补齐 service/user/{dtos,service,spec}.py（与 sprint/task 文件结构对等）；测试统一迁到 tests/test_<domain>_methods.py；UserSummary 沉淀为单一来源被 task/dtos 引用
• 决策引导清晰：phase3.md 重组为「推荐默认组合」(4) + 「可选扩展」(2) + 「决策引导」；虚拟实体 / 跨层数据流 / 3.0 MCP 迁移各补 10~20 行内联摘要（用户不点外链即可决策）
• spec-management 工作流：新增 ## 语言要求（FR-008）与 ## 从旧结构迁移（FR-009，含 spec 编号保留规则与跳过 Phase 0 判定标准）

Changes

Skill 文档（skill/）

• SKILL.md：删 argument-hint；新增适用版本 + 调用约定 + 阶段导航；Phase 0 整体迁出；项目结构段补 tests/；ASCII 框图路径简化
• phases/phase0.md（新）：Step 0-1~0-8 完整外置；Step 0-3 含虚拟实体 10 行内联摘要；末尾「老用户迭代」章节
• phases/phase1~4.md：路径统一为 specs/<编号>-<需求简述>/phaseN.md；移除散落的「3.0 起 / 3.2+」版本门槛
• phases/phase3.md：出口分级 + 跨层数据流摘要 + UseCase MCP 版本演进摘要
• spec-management.md：新增 ## 语言要求 + ## 从旧结构迁移

Skill 模板（skill/template/）

• src/service/user/{dtos,service,spec}.py（新）：补齐与 sprint/task 对等的文件结构；UserService 含 list_users + create_user
• src/service/task/dtos.py：UserSummary 改为从 user/dtos 引用（单一来源，消除重复定义）
• src/main.py：默认仅 REST + UseCase MCP + Voyager + GraphQL HTTP；JSON-RPC / CLI 注释化；base 实体层 MCP（create_mcp_server）加层级注释；注册 UserService
• tests/（新）：conftest.py（in-memory sqlite + monkey-patch session）+ 三 service 测试共 10 cases
• pyproject.toml：新增 persist / persist-pg / persist-mysql optional 组；修复 persist-pg/persist-mysql self-reference（避免被解析为 PyPI persist 包，详见 code-review finding support basic graphql functions #1）
• 删除 src/router/（手写 router 残留）与 service/{sprint,task}/test.py（空占位）

Spec / Design artifacts

specs/006-skill-template-polish/：spec → clarify (5 决策) → plan → research → data-model → contracts/skill-interface → quickstart → tasks (38 项) → checklists (requirements + documentation) → baseline → vv-result。

Test plan

quickstart.md 全 6 组检查：

• 检查 1 自洽性：5/5 子项 PASS（grep spec/phase 仅余 1 处迁移表的合理保留）
• 检查 2 入口总览：phases/phase0.md 存在（240 行）；SKILL.md 含 ## 适用版本 + ## 调用约定；散落版本门槛清理（phase1/2/4=0，phase3=1 合理保留）
• 检查 3 模板可运行：uv sync --all-extras && uvicorn src.main:app 启动；/voyager/ / /graphql / /openapi.json / /api/user_service/list_users 全部 HTTP 200
• 检查 4 测试位置与运行：pytest tests/ → 10 passed（3 user + 3 sprint + 4 task，覆盖正常 + 边界场景）
• 检查 5 核心概念自包含：虚拟实体 / 跨层数据流 / UseCase MCP 版本演进 内联摘要到位
• 检查 6 spec-management 完整性：含 ## 语言要求 + ## 从旧结构迁移

/code-review medium 自检：

• Finding support basic graphql functions #1 CONFIRMED 已修复（pyproject.toml self-reference，commit 86520ca）；verifier 实测 uv sync --extra persist-pg 现装 alembic 1.18.5 + asyncpg，不再装 PyPI persist / zope-interface / six

• Finding fix(demo): add missing dependency greenlet to demo group #2 PLAUSIBLE 接受为技术债（conftest 未 patch er._session_factory / Resolver / graphql_handler；当前 methods 层测试够用，已加注释标记）

• 5 项 REFUTED 记录在 vv-result.md 防止重复发现

• 请人工验证（自动化无法评测）：

  • SC-001：有 FastAPI 基础但未用过 nexusx 的开发者，从打开 skill 到产出可运行 Phase 1 项目 ≤30 分钟
  • SC-004：抽 phase2.md 独立阅读，5 题理解度问题答对 ≥4

🤖 Generated with Claude Code